<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
<!Converted with LaTeX2HTML 95 (Thu Jan 19 1995) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
<HEAD>
<TITLE> QMATRIX(3LAS)</TITLE>
</HEAD>
<BODY>
<meta name="description" value=" QMATRIX(3LAS)">
<meta name="keywords" value="html">
<meta name="resource-type" value="document">
<meta name="distribution" value="global">
<P>
 <BR> <HR><A NAME=tex2html443 HREF="node26.html"><IMG ALIGN=BOTTOM ALT="next" SRC="next_motif.gif"></A> <A NAME=tex2html441 HREF="node15.html"><IMG ALIGN=BOTTOM ALT="up" SRC="up_motif.gif"></A> <A NAME=tex2html435 HREF="node24.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="previous_motif.gif"></A> <A NAME=tex2html445 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="contents_motif.gif"></A>   <A HREF="node28.html#SectionIndex"><IMG ALIGN=BOTTOM ALT="index" SRC="index_motif.gif"></A> <BR>
<B> Next:</B> <A NAME=tex2html444 HREF="node26.html"> RTC(3LAS)</A>
<B>Up:</B> <A NAME=tex2html442 HREF="node15.html"> Manual Pages</A>
<B> Previous:</B> <A NAME=tex2html436 HREF="node24.html"> PRECOND(3LAS)</A>
<BR> <HR> <P>
<H2><A NAME=SECTION000810000000000000000>&#160;</A><A NAME=QMATRIX> QMATRIX(3LAS)</A></H2>
<P>
<P>

<H3><A NAME=SECTION000810100000000000000> NAME</A></H3>
<P>

<P>
<tt> Q_Constr</tt>, <tt> Q_Destr</tt>, 
<tt> Q_SetName</tt>, <tt> Q_GetName</tt>,
<tt> Q_GetDim</tt>, <tt> Q_GetSymmetry</tt>, <tt> Q_GetElOrder</tt>,
<tt> Q_SetLen</tt>, <tt> Q_GetLen</tt>,
<tt> Q_SetEntry</tt>, <tt> Q_GetPos</tt>, <tt> Q_GetVal</tt>, <tt> Q_AddVal</tt>, 
<tt> Q__SetEntry</tt>, <tt> Q__GetPos</tt>, <tt> Q__GetVal</tt>, <tt> Q__AddVal</tt>, 
<tt> Q_GetEl</tt>,
<tt> Q_SortEl</tt>, <tt> Q_AllocInvDiagEl</tt>,
<tt> Q_SetKer</tt>, <tt> Q_KerDefined</tt>,
<tt> Q_EigenvalInfo</tt>,
<tt> Q_Lock</tt>, <tt> Q_Unlock</tt>
-- type <tt> QMatrix</tt> for quadratic sparse matrices
<P>

<H3><A NAME=SECTION000810200000000000000> SYNOPSIS</A></H3>
<P>

<P>

<PRE>#include &lt;laspack/qmatrix.h&gt;

typedef double Real; 

typedef enum { 
    Rowws, 
    Clmws 
} ElOrderType; 

typedef enum { 
    Normal, 
    Tempor 
} InstanceType; 

void Q_Constr(QMatrix *Q, char *Name, size_t Dim, Boolean Symmetry, 
         ElOrderType ElOrder, InstanceType Instance, Boolean OwnData); 
void Q_Destr(QMatrix *Q); 
void Q_SetName(QMatrix *Q, char *Name); 
char *Q_GetName(QMatrix *Q); 
size_t Q_GetDim(QMatrix *Q); 
Boolean Q_GetSymmetry(QMatrix *Q); 
ElOrderType Q_GetElOrder(QMatrix *Q); 
void Q_SetLen(QMatrix *Q, size_t RoC, size_t Len); 
size_t Q_GetLen(QMatrix *Q, size_t RoC); 
void Q_SetEntry(QMatrix *Q, size_t RoC, size_t Entry, size_t Pos, Real Val); 
size_t Q_GetPos(QMatrix *Q, size_t RoC, size_t Entry); 
Real Q_GetVal(QMatrix *Q, size_t RoC, size_t Entry); 
void Q_AddVal(QMatrix *Q, size_t RoC, size_t Entry, Real Val); 
void Q__SetEntry(QMatrix *Q, size_t RoC, size_t Entry, size_t Pos, Real Val); 
size_t Q__GetPos(QMatrix *Q, size_t RoC, size_t Entry); 
Real Q__GetVal(QMatrix *Q, size_t RoC, size_t Entry); 
void Q__AddVal(QMatrix *Q, size_t RoC, size_t Entry, Real Val); 
Real Q_GetEl(QMatrix *Q, size_t Row, size_t Clm); 
void Q_SortEl(QMatrix *Q); 
void Q_AllocInvDiagEl(QMatrix *Q); 
void Q_SetKer(QMatrix *Q, Vector *RightKer, Vector *LeftKer); 
Boolean Q_KerDefined(QMatrix *Q); 
void **Q_EigenvalInfo(QMatrix *Q); 
void Q_Lock(QMatrix *Q); 
void Q_Unlock(QMatrix *Q);
</PRE>
<H3><A NAME=SECTION000810300000000000000> DESCRIPTION</A></H3>
<P>
<H6><A NAME=Q_Constr>&#160;</A></H6>
The procedure <tt> Q_Constr</tt> is the constructor of the type <tt> QMatrix</tt>. 
It creates and initializes a new variable of this type directed
by the parameter <tt> Q</tt>.
As symbolic name, the string <tt> Name</tt> is used.
The dimensions of the matrix are defined by <tt> Dim</tt>.
The parameter <tt> Symmetry</tt> should be set to <tt> True</tt>
for symmetric matrices,
to <tt> False</tt> for non-symmetric matrices.
The parameter <tt> ElOrder</tt> determines the order in which the matrix elements
are stored.
It can be set to <tt> Rowws</tt> and <tt> Clmws</tt> for row-wise and column-wise
ordering, respectively.
For matrices used in application codes,
one should always use the parameters
<tt> Instance = Normal</tt> and <tt> OwnData = True</tt>.
In this case, <tt> Q_Constr</tt> allocates memory for internal auxiliary
variables needed for storage of matrix elements and initializes them.
Other parameter combinations for <tt> Instance</tt> and <tt> OwnData</tt>
are intended for internal usage by <tt> LASPack</tt>
 .
<P>
<H6><A NAME=Q_Destr>&#160;</A></H6>
The procedure <tt> Q_Destr</tt> is the destructor of type <tt> QMatrix</tt>.
It releases memory of matrix elements as well as internal auxiliary variables.
<P>
<H6><A NAME=Q_SetName>&#160;</A><A NAME=Q_GetName>&#160;</A></H6>
The procedure <tt> Q_SetName</tt> resets the symbolic name of the matrix.
This can be queried by the procedure <tt> Q_GetName</tt>.
<P>
<H6><A NAME=Q_GetDim>&#160;</A></H6>
The procedure <tt> Q_GetDim</tt> returns the dimension of the matrix.
<P>
<H6><A NAME=Q_GetSymmetry>&#160;</A></H6>
The procedure <tt> Q_GetSymmetry</tt> returns <tt> True</tt> if <tt> Q</tt> is stored
as a symmetric matrix, <tt> False</tt> otherwise.
<P>
<H6><A NAME=Q_GetElOrder>&#160;</A></H6>
The procedure <tt> Q_GetElOrder</tt> returns the element order
of matrix elements.
<P>
<H6><A NAME=Q_SetLen>&#160;</A><A NAME=Q_GetLen>&#160;</A></H6>
The procedure <tt> Q_SetLen</tt> sets or resets the length, 
i.e. the number of non-zero elements,
of the row or column <tt> RoC</tt> 
<tt> (1 &lt;= RoC &lt;= Dim)</tt>

to <tt> Len</tt>,
and allocates memory for element storage.
The length of each row or column is initialized by zero.
The current value can be queried by the procedure <tt> Q_GetLen</tt>.
<P>
<H6><A NAME=Q_SetEntry>&#160;</A></H6>
The procedure <tt> Q_SetEntry</tt> assigns the position <tt> Pos</tt> and
the value <tt> Val</tt> of a non-zero element in the row or column <tt> RoC</tt>
to the entry <tt> Entry</tt>
<tt> (0 &lt;= Entry &lt;= Len - 1)</tt>.

For symmetric matrices, only elements of the upper triangular part
should be stored.
<P>
<H6><A NAME=Q_GetPos>&#160;</A><A NAME=Q_GetVal>&#160;</A></H6>
The procedures <tt> Q_GetPos</tt> and <tt> Q_GetVal</tt> return the position and
the value of the non-zero element stored as entry <tt> Entry</tt>
in the row or column <tt> RoC</tt>, respectively.
<P>
<H6><A NAME=Q_AddVal>&#160;</A></H6>
The procedure <tt> Q_AddEntry</tt> adds the value <tt> Val</tt>
to the non-zero element stored as entry <tt> Entry</tt>
in the row or column <tt> RoC</tt>.
<P>
<H6><A NAME=Q__SetEntry>&#160;</A><A NAME=Q__GetPos>&#160;</A><A NAME=Q__GetVal>&#160;</A><A NAME=Q__AddVal>&#160;</A></H6>
The procedures <tt> Q__GetLen</tt>, <tt> Q__SetEntry</tt>, <tt> Q__GetPos</tt>,
<tt> Q__GetVal</tt> and <tt> Q__AddVal</tt> have the same functionality as
the routines <tt> Q_GetLen</tt>, <tt> Q_SetEntry</tt>, <tt> Q_GetPos</tt>,
<tt> Q_GetVal</tt> and <tt> Q_AddVal</tt>.
They are designed as preprocessing macros and are thus essentially faster.
Because no range check is made they should not be used in the test
phase of the application code.
<P>
<H6><A NAME=Q_GetEl>&#160;</A></H6>
The procedure <tt> Q_GetEl</tt> returns the value of the matrix element
in the row <tt> Row</tt> and the column <tt> Clm</tt>.
In contrast to other procedures, all matrix elements are considered here.
If any element is not stored, zero is returned.
<P>
<H6><A NAME=Q_SortEl>&#160;</A></H6>
The procedure <tt> Q_SortEl</tt> sorts elements of each row or column
in ascending order.
<P>
<H6><A NAME=Q_AllocInvDiagEl>&#160;</A></H6>
The procedure <tt> Q_AllocInvDiagEl</tt> allocates pointers 
to the diagonal elements and computes and stores their reciprocal values 
as auxiliary variables.
<P>
<H6><A NAME=Q_SetKer>&#160;</A><A NAME=Q_KerDefined>&#160;</A></H6>
For singular matrices, a one-dimensional ``right'' and ``left'' null space
can be defined by the procedure <tt> Q_SetKer</tt> with vectors <tt> RightKer</tt>
and <tt> LeftKer</tt> as parameter.
For symmetric matrices, the ``left'' null space equals the ``right'' one
and therefore need not be set.
The procedure <tt> Q_KerDefined</tt> returns <tt> True</tt> if a null space
was specified, otherwise <tt> False</tt>.
<P>
<H6><A NAME=Q_EigenvalInfo>&#160;</A></H6>
The procedure <tt> Q_EigenvalInfo</tt> is used in <tt> LASPack</tt>
  internally.
It allows us to read and store information above eigenvalues
of the matrix <tt> Q</tt>,
which are produced by routines in the module <A HREF="node17.html#EIGENVAL"><b> EIGENVAL</b></A>,
in connection with the matrix itself.
The query of these data by the procedure <tt> Q_EigenvalInfo</tt>
avoid an access to the internal representation of the type <tt> QMatrix</tt>.
<P>
<H6><A NAME=Q_Lock>&#160;</A><A NAME=Q_Unlock>&#160;</A></H6>
In subroutines, the procedure <tt> Q_Lock</tt> should be applied
to all passed parameters of the type <tt> QMatrix</tt>.
This ensures that,
if they are of a temporary kind,
they are not released within any <tt> LASPack</tt>
  routine
before the procedure is left.
This should be carried out by a call of <tt> Q_Unlock</tt>
which has to be called at the end of the procedure.
<P>
<H3><A NAME=SECTION000810400000000000000> FILES</A></H3>
<P>
  <tt> qmatrix.h ... </tt> header file <BR> 

  <tt> qmatrix.c ... </tt> source file
<P>
<H3><A NAME=SECTION000810500000000000000> EXAMPLES</A></H3>
<P>
<H6><A NAME=QMATRIXExample>&#160;</A></H6>
<P>
A simple tridiagonal 7 x 7
 matrix

<PRE>       |  2   -1           |
   1   | -1    2   -1      |
  ---  |           ...     |
   h   |       1    2   -1 |
       |           -1    2 |
</PRE>
<P>
with <tt> h = 1/8</tt>
 could be generated as follows:

<PRE>QMatrix A;
size_t Row;
double h;

...

Q_Constr(&amp;A, &quot;A&quot;, 7, False, Rowws, Normal, True);

h = 1.0 / 8.0;

Q_SetLen(&amp;A, 1, 2);
Q_SetEntry(&amp;A, 1, 0, 1,  2.0 / h);       
Q_SetEntry(&amp;A, 1, 1, 2, -1.0 / h);      
for (Row = 2; Row &lt; 7; Row++) {
    Q_SetLen(&amp;A, Row, 3);
    Q_SetEntry(&amp;A, Row, 0, Row - 1, -1.0 / h);      
    Q_SetEntry(&amp;A, Row, 1, Row,      2.0 / h);      
    Q_SetEntry(&amp;A, Row, 2, Row + 1, -1.0 / h);
}
Q_SetLen(&amp;A, 7, 2);
Q_SetEntry(&amp;A, 7, 0, 6, -1.0 / h);      
Q_SetEntry(&amp;A, 7, 1, 7,  2.0 / h);      

...

Q_Destr(&amp;A);
</PRE>
<P>
<H3><A NAME=SECTION000810600000000000000> SEE ALSO</A></H3>
<P>
<A HREF="node21.html#MATRIX">matrix(3LAS)</A>, <A HREF="node23.html#OPERATS">operats(3LAS)</A>, 
<A HREF="node18.html#ERRHANDL">errhandl(3LAS)</A>
<P>
<BR> <HR><A NAME=tex2html443 HREF="node26.html"><IMG ALIGN=BOTTOM ALT="next" SRC="next_motif.gif"></A> <A NAME=tex2html441 HREF="node15.html"><IMG ALIGN=BOTTOM ALT="up" SRC="up_motif.gif"></A> <A NAME=tex2html435 HREF="node24.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="previous_motif.gif"></A> <A NAME=tex2html445 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="contents_motif.gif"></A>   <A HREF="node28.html#SectionIndex"><IMG ALIGN=BOTTOM ALT="index" SRC="index_motif.gif"></A> <BR>
<B> Next:</B> <A NAME=tex2html444 HREF="node26.html"> RTC(3LAS)</A>
<B>Up:</B> <A NAME=tex2html442 HREF="node15.html"> Manual Pages</A>
<B> Previous:</B> <A NAME=tex2html436 HREF="node24.html"> PRECOND(3LAS)</A>
<BR> <HR> <P>
<BR> <HR>
<P><ADDRESS>
Tomas Skalicky (skalicky@msmfs1.mw.tu-dresden.de)
</ADDRESS>
</BODY>
</BODY>
